diff --git a/README.md b/README.md
new file mode 100644
index 0000000..2366e08
--- /dev/null
+++ b/README.md
@@ -0,0 +1,65 @@
+# Structured Output with Union Events API
+
+This repository contains a small CLI tool that demonstrates how to parse raw log lines into typed events using **LangChain**'s structured output capabilities and **Pydantic v2**.
+
+## Features
+
+* Two event models:
+  * `HttpOkEvent` – successful HTTP request (status 200)
+  * `HttpErrorEvent` – error response (4xx/5xx)
+* Uses a discriminator field (`kind`) to route the parsed data into the correct model.
+* Parses each log line with an LLM via LangChain and returns a validated Pydantic object.
+* Prints a simple table of all parsed events.
+
+## Requirements
+
+```text
+langchain-core>=1.0
+langchain-openai
+pydantic>=2
+python-dotenv
+```
+
+Install them with:
+
+```bash
+pip install -r requirements.txt
+```
+
+> **Note**: The script uses the `gpt-4o-mini` model by default. Set the environment variable `OPENAI_API_KEY` to your key.
+
+## Usage
+
+### From a file
+
+```bash
+python main.py --file logs.txt
+```
+
+### From stdin
+
+```bash
+echo -e "GET /api/v1/users 200 123ms\nPOST /api/v1/login 404 Not Found" | python main.py
+```
+
+The output will look like:
+
+```
+kind | path          | status | duration_ms | error_message
+-----+---------------+--------+-------------+--------------
+ok   | /api/v1/users | 200    | 123         |
+error| /api/v1/login | 404    |             | Not Found
+```
+
+## How it works
+
+The script builds a LangChain chain that:
+
+1. **Prompts** the LLM to parse a single log line into JSON.
+2. Uses `PydanticOutputParser` to validate and convert the JSON into one of the two Pydantic models.
+3. Collects all parsed events and prints them in a table.
+
+The union type is handled automatically by LangChain's structured output parser thanks to the discriminator field.
+
+## License
+MIT © 2026