civiclens 0.3.0__py3-none-any.whl

civiclens/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

civiclens/cli.py

@@ -0,0 +1,151 @@
+import argparse
+import os
+from enum import Enum
+from civiclens.utils import add_ingest_cmd, add_query_cmd, add_info_cmd
+from civiclens import __version__
+from civiclens.llm import add_prompt_cmd
+from civiclens.demo import PromptCommand
+
+class Audience(str, Enum):
+    youth = "youth"
+    executive = "executive"
+    child = "child"
+
+def positive_int(value):
+    """
+    Converts a string to a positive integer.
+
+    Args:
+        value (str): The string to convert to an integer
+
+    Returns:
+        int: The converted integer
+
+    Raises:
+        argparse.ArgumentTypeError: If the value is not a positive integer
+    """
+    ivalue = int(value)
+    if ivalue <= 0:
+        raise argparse.ArgumentTypeError("Value must be > 0")
+    return ivalue
+
+
+
+EPILOG = """
+Examples:
+==================================
+Ingest documents from an S3 bucket:
+  civiclens ingest \\
+      --source s3 \\
+      --path s3://eo-archive \\
+      --chunk-size 1200
+
+Query the system with audience adaptation:
+  civiclens query "How does this EO affect education?" --audience teen
+
+Query with retrieval depth and source transparency:
+  civiclens query "How does this executive order affect education?" \\
+      --audience teen \\
+      --top-k 5 \\
+      --show-sources
+
+Evaluate RAG system performance using benchmark data:
+  civiclens eval \\
+      --dataset benchmarks/eo_questions.json \\
+      --metrics faithfulness answer_relevance context_recall context_precision \\
+      --top-k 5 \\
+      --save-results
+      
+Copyright © 2026 CivicLens AI
+"""
+
+
+def main():
+    
+    """
+    Main function for the CivicLens AI CLI.
+
+    This function parses command line arguments using argparse and calls
+    the appropriate sub-command function based on the value of the
+    'command' argument.
+
+    The available sub-commands are ingest, query, and eval.
+
+    The ingest command ingests documents into the vector database.
+
+    The query command generates a civic summary for a given set of
+    documents.
+
+    The eval command evaluates the performance of the model on a
+    given set of documents.
+
+    """
+    parser = argparse.ArgumentParser(
+        prog="civiclens",
+        epilog=EPILOG,
+        description="CivicLens AI – Document analysis and civic summarization CLI",
+        formatter_class=argparse.RawDescriptionHelpFormatter
+    )
+
+    parser.add_argument(
+        "--config",
+        "-c",
+        type=str,
+        help="Path to YAML or JSON config file"
+    )
+
+    parser.add_argument(
+        "--openai-key",
+        "--api-key",
+        default=os.getenv("OPENAI_API_KEY"),
+        help="OpenAI API key",
+        required=False
+    )
+    
+    parser.add_argument(
+        "--audience",
+        "-a",
+        choices=[a.value for a in Audience],
+        default=Audience.youth.value
+    )
+    
+    parser.add_argument(
+        "--top-k", 
+        "-k",
+        type=positive_int, 
+        default=5
+    )
+    
+    parser.add_argument(
+        "--version",
+        "-v",
+        action="version",
+        version=f"%(prog)s {__version__}",
+        help="Show the version number and exit"
+    )
+
+    subparsers = parser.add_subparsers(
+        title="Available Commands",
+        dest="command",
+        required=True
+    )
+
+    # add commands
+    add_ingest_cmd(subparsers)
+    add_query_cmd(subparsers)
+    add_info_cmd(subparsers)
+    add_prompt_cmd(subparsers)
+    
+    # PromptCommand.add_to_subparsers(subparsers)
+
+
+    try:
+        args = parser.parse_args()
+        args.func(args)
+    except SystemExit:
+        print("Use --help to see available commands.")
+        raise
+
+
+if __name__ == "__main__":
+    main()

civiclens/demo.py

@@ -0,0 +1,168 @@
+import json
+import requests
+from rich.console import Console
+from rich.panel import Panel
+from rich.markdown import Markdown
+
+
+class LLMConsoleRenderer:
+    """Handles rendering LLM output to the terminal using Rich."""
+
+    def __init__(self):
+        self.console = Console()
+
+    def print_response(self, response: str) -> None:
+        """
+        Prints a formatted panel containing the LLM response.
+        """
+        self.console.print(
+            Panel(
+                Markdown(response),
+                title="🤖 LLM Response",
+                border_style="cyan",
+                padding=(1, 2),
+            )
+        )
+
+    def stream_response(self, chunks) -> None:
+        """
+        Streams a sequence of chunks from an LLM response.
+        """
+        self.console.print("\n🤖 LLM Response\n", style="bold cyan")
+        with self.console.status("Thinking...", spinner="dots"):
+            for chunk in chunks:
+                self.console.print(chunk, end="", style="green")
+
+
+class LLMClient:
+    """Client for querying a local or remote LLM endpoint."""
+
+    def __init__(
+        self,
+        url: str = "http://localhost:11434/api/chat",
+        model: str = "gpt-oss:20b",
+        temperature: float = 0.0,
+        max_tokens: int = 2048,
+        renderer: LLMConsoleRenderer | None = None,
+        timeout: int = 60,
+    ):
+        self.url = url
+        self.model = model
+        self.temperature = temperature
+        self.max_tokens = max_tokens
+        self.timeout = timeout
+        self.renderer = renderer or LLMConsoleRenderer()
+
+    def query(self, prompt: str) -> str:
+        """
+        Query the model and return the full response text.
+        """
+        payload = {
+            "model": self.model,
+            "messages": [
+                {
+                    "role": "user",
+                    "content": prompt.strip(),
+                }
+            ],
+            "options": {
+                "seed": 123,
+                "temperature": self.temperature,
+                "num_ctx": self.max_tokens,
+            },
+        }
+
+        response_text = ""
+
+        with requests.post(
+            self.url,
+            json=payload,
+            stream=True,
+            timeout=self.timeout,
+        ) as response:
+            response.raise_for_status()
+
+            for line in response.iter_lines(decode_unicode=True):
+                if not line:
+                    continue
+
+                data = json.loads(line)
+                if "message" in data:
+                    response_text += data["message"]["content"]
+
+        return response_text
+
+    def query_and_render(self, prompt: str) -> None:
+        """
+        Query the model and print the formatted response.
+        """
+        response = self.query(prompt)
+        self.renderer.print_response(response)
+
+
+class PromptCommand:
+    """CLI command registration and handler."""
+
+    @staticmethod
+    def add_to_subparsers(subparsers):
+        """
+        Adds the `prompt` command to the CLI.
+        """
+        parser = subparsers.add_parser(
+            "prompt",
+            help="Ask a question to the model",
+        )
+
+        parser.add_argument(
+            "question",
+            type=str,
+            default="Hello, how can I help you?",
+            help="The question to ask the model",
+        )
+
+        parser.add_argument(
+            "--temperature",
+            "-t",
+            type=float,
+            default=0.0,
+            help="The temperature value for the model (default: 0.0)",
+        )
+
+        parser.add_argument(
+            "--max-tokens",
+            "-m",
+            type=int,
+            default=2048,
+            help="The maximum number of tokens to generate (default: 2048)",
+        )
+
+        parser.add_argument(
+            "--model",
+            type=str,
+            default="gpt-oss:20b",
+            help="The model to query (default: gpt-oss:20b)",
+        )
+
+        parser.add_argument(
+            "--url",
+            "-u",
+            type=str,
+            default="http://localhost:11434/api/chat",
+            help="The URL of the model to query",
+        )
+
+        parser.set_defaults(func=PromptCommand.run)
+
+    @staticmethod
+    def run(args):
+        """
+        CLI entrypoint for the prompt command.
+        """
+        client = LLMClient(
+            url=args.url,
+            model=args.model,
+            temperature=float(args.temperature),
+            max_tokens=int(args.max_tokens),
+        )
+
+        client.query_and_render(args.question)

civiclens/llm.py

@@ -0,0 +1,151 @@
+import json
+import requests
+from rich.console import Console
+from rich.panel import Panel
+from rich.markdown import Markdown
+
+console = Console()
+
+
+def print_llm_response(response: str):
+    """
+    Prints a formatted panel containing the LLM response.
+
+    Args:
+        response (str): The LLM response to print.
+    """
+    console.print(
+        Panel(
+            Markdown(response),
+            title="🤖 LLM Response",
+            border_style="cyan",
+            padding=(1, 2),
+        )
+    )
+
+def stream_llm_response(chunks):
+    """
+    Stream a sequence of chunks from an LLM response to the console.
+
+    :param chunks: An iterable of strings, where each string is a chunk of the LLM response.
+    """
+    console.print("\n🤖 LLM Response\n", style="bold cyan")
+    with console.status("Thinking...", spinner="dots"):
+        for chunk in chunks:
+            console.print(chunk, end="", style="green")
+            
+            
+
+def query_model(args):
+    # Create the data payload as a dictionary
+ 
+    """
+    Query a model using the provided prompt and parameters.
+
+    Parameters:
+    prompt (str): The input to the model.
+    stream (bool, optional): Whether to stream the response. Defaults to True.
+    model (str, optional): The model to query. Defaults to "gpt-oss:20b".
+    temperature (float, optional): The temperature value for the model. Defaults to 0.0.
+    max_tokens (int, optional): The maximum number of tokens to generate. Defaults to 2048.
+    url (str, optional): The URL of the model to query. Defaults to "http://localhost:11434/api/chat".
+
+    Returns:
+    str: The output of the model.
+
+    """
+    url = args.url
+    prompt = args.question.strip()
+    model = args.model
+    temperature = float(args.temperature)
+    max_tokens = int(args.max_tokens)
+
+    data = {
+        "model": model,
+        "messages": [
+            {
+                "role": "user",
+                "content": prompt
+            }
+        ],
+        "options": {     # Settings below are required for deterministic responses
+            "seed": 123,
+            "temperature": temperature,
+            "num_ctx": max_tokens
+        }
+    }
+
+    # Send the POST request
+    with requests.post(url, json=data, stream=True, timeout=60) as r:
+        r.raise_for_status()
+        response_data = ""
+        for line in r.iter_lines(decode_unicode=True):
+            if not line:
+                continue
+            response_json = json.loads(line)
+            if "message" in response_json:
+                response_data += response_json["message"]["content"]
+
+    # Print the LLM response
+    # if stream:
+    #     stream_llm_response(response_data)
+    # else:
+    print_llm_response(response=response_data)
+
+
+def add_prompt_cmd(subparsers):
+    """
+    Adds the query command to the CLI.
+
+    The query command asks a question to the model.
+
+    The available arguments are:
+    - question: The question to ask the model
+    - --temperature or -t: The temperature value for the model (default: 0.0)
+    - --max-tokens or -m: The maximum number of tokens to generate (default: 2048)
+    """
+    query = subparsers.add_parser(
+        "prompt",
+        help="Ask a question to the model")
+
+    query.add_argument(
+        "question", 
+        type=str,
+        default="Hello, how can I help you?",
+        help="The question to ask the model"
+    )
+
+    query.add_argument(
+        "--temperature",
+        "-t",
+        type=float,
+        default=0.0,
+        help="The temperature value for the model (default: 0.0)"
+    )
+
+    query.add_argument(
+        "--max-tokens",
+        "-m",
+        type=int,
+        default=2048,
+        help="The maximum number of tokens to generate (default: 2048)"
+    )
+    
+    query.add_argument(
+        "--model",
+        type=str,
+        default="gpt-oss:20b",
+        help="The model to query (default: gpt-oss:20b)"
+    )
+    
+    query.add_argument(
+        "--url",
+        "-u",
+        type=str,
+        default="http://localhost:11434/api/chat",
+        help="The URL of the model to query (default: http://localhost:11434/api/chat)"
+    )
+
+    query.set_defaults(func=query_model)
+    
+    

civiclens/utils.py

@@ -0,0 +1,402 @@
+import argparse
+
+
+def run_ingest(args):
+    """
+    Ingests documents into the vector database.
+
+    Args:
+        args: Parsed argparse arguments containing the ingest command arguments
+    """
+    print(f"Ingesting from {args.source} at {args.path}")
+    
+def add_info_cmd(subparsers):
+    info = subparsers.add_parser(
+        "info",
+        help="Display information about CivicLens AI"
+    )
+
+    info.add_argument(
+        "--short",
+        "-s",
+        action="store_true",
+        help="Show a brief description only"
+    )
+    
+    info.add_argument(
+        "--json",
+        action="store_true",
+        help="Output system information in JSON format"
+    )
+
+    info.set_defaults(func=run_info)
+
+
+def add_ingest_cmd(subparsers):
+    """
+    Adds the ingest command to the CLI.
+
+    The ingest command ingests documents into the vector database.
+
+    The available arguments are:
+    - --source: The document source (local or s3)
+    - --path: The directory path or S3 bucket URI of the documents to ingest
+    - --chunk-size: The number of documents to ingest at once (default: 1000)
+    """
+    ingest = subparsers.add_parser(
+        "ingest",
+        aliases=["i"],
+        help="Ingest documents into the vector database"
+    )
+
+    ingest.add_argument(
+        "--source",
+        "-s",
+        required=True,
+        choices=["local", "s3"],
+        help="Document source"
+    )
+
+    ingest.add_argument(
+        "--path",
+        "-p",
+        required=True,
+        help="Directory path or S3 bucket URI"
+    )
+
+    ingest.add_argument(
+        "--chunk-size",
+        "-cs",
+        type=int,
+        default=1000
+    )
+
+    ingest.set_defaults(func=run_ingest)
+
+
+def add_query_cmd(subparsers):
+    """
+    Adds the query command to the CLI.
+
+    The query command generates a civic summary for a given set of
+    documents.
+
+    The available arguments are:
+    - question: The question to be answered by the civic summary
+    - --audience: The target audience for the civic summary
+    - --top-k: The number of civic summaries to return
+    - --show-sources: A boolean indicating whether to show the sources of the civic summaries
+    """
+    query = subparsers.add_parser(
+        "query", 
+        aliases=["q"],
+        help="Generate a civic summary for a given question")
+
+    query.add_argument("question", type=str)
+
+    query.add_argument(
+        "--audience",
+        "-a",
+        choices=["child", "teen", "executive"],
+        default="teen"
+    )
+
+    query.add_argument(
+        "--top-k",
+        "-k",
+        type=int, 
+        default=5
+    )
+    query.add_argument(
+        "--show-sources",
+        "-s",
+        action="store_true"
+    )
+
+    query.set_defaults(func=run_query)
+
+# def run_eval(args):
+#     """
+#     Run RAG evaluation on a benchmark dataset.
+#     """
+#     print("\n📊 Running CivicLens RAG Evaluation")
+#     print(f"Dataset: {args.dataset}")
+#     print(f"Metrics: {', '.join(args.metrics)}")
+#     print(f"Top-K: {args.top_k}")
+#     print("-" * 60)
+
+#     dataset = load_eval_dataset(args.dataset)
+
+#     results = []
+
+#     for i, record in enumerate(dataset, 1):
+#         question = record["question"]
+#         ground_truth = record.get("ground_truth")
+
+#         docs = retrieve_documents(
+#             query=question,
+#             top_k=args.top_k
+#         )
+
+#         answer, _ = generate_answer_and_summary(
+#             question=question,
+#             documents=docs,
+#             audience="executive"
+#         )
+
+#         metrics = evaluate_answer(
+#             question=question,
+#             answer=answer,
+#             documents=docs,
+#             ground_truth=ground_truth,
+#             metrics=args.metrics
+#         )
+
+#         results.append({
+#             "test_number": i,
+#             "question": question,
+#             "answer": answer,
+#             "ground_truth": ground_truth,
+#             "metrics": metrics
+#         })
+
+#         print(f"✔ Test {i} completed")
+
+#     summary = aggregate_metrics(results)
+
+#     print("\n📈 Evaluation Summary")
+#     for k, v in summary.items():
+#         print(f"{k}: {v:.4f}")
+
+#     if args.save_results:
+#         save_eval_results(results, summary, args.project)
+
+
+# def add_eval_cmd(subparsers):
+#     eval_cmd = subparsers.add_parser(
+#         "eval",
+#         help="Evaluate RAG system performance on a benchmark dataset"
+#     )
+
+#     eval_cmd.add_argument(
+#         "--dataset",
+#         required=True,
+#         help="Path to evaluation dataset (JSON, JSONL, or CSV)"
+#     )
+
+#     eval_cmd.add_argument(
+#         "--project",
+#         default="civiclens_evaluation",
+#         help="Evaluation project name"
+#     )
+
+#     eval_cmd.add_argument(
+#         "--metrics",
+#         nargs="+",
+#         choices=[
+#             "faithfulness",
+#             "answer_relevance",
+#             "context_recall",
+#             "context_precision"
+#         ],
+#         default=[
+#             "faithfulness",
+#             "answer_relevance",
+#             "context_recall",
+#             "context_precision"
+#         ],
+#         help="Evaluation metrics to compute"
+#     )
+
+#     eval_cmd.add_argument(
+#         "--top-k",
+#         type=int,
+#         default=5,
+#         help="Number of retrieved documents per query"
+#     )
+
+#     eval_cmd.add_argument(
+#         "--save-results",
+#         action="store_true",
+#         help="Save evaluation results to disk"
+#     )
+
+#     eval_cmd.set_defaults(func=run_eval)
+
+
+def retrieve_documents(query: str, top_k: int):
+    """
+    Retrieve top-k documents from the vector store.
+    """
+    # Example: vector_db.similarity_search(query, k=top_k)
+    return "Retrieved Documents"
+
+def generate_answer_and_summary(question, documents, audience):
+    """
+    Generate a grounded answer and summary using retrieved documents.
+    """
+    # context = "\n\n".join(doc.page_content for doc in documents)
+
+    # prompt = USER_PROMPT_TEMPLATE.format(
+    #     input=question,
+    #     context=context
+    # )
+
+    # response = llm.invoke(prompt)
+
+    # Expected format:
+    # ANSWER:
+    # ...
+    # SUMMARY:
+    # ...
+    return f"{question, documents, audience}" # parse_answer_and_summary(response)
+
+    
+def run_query(args):
+    """
+    Execute a RAG query with audience-aware output.
+    """
+    # 1. Resolve configuration
+    audience = args.audience
+    top_k = args.top_k
+    show_sources = args.show_sources
+    question = args.question
+
+    print(f"\n🔍 Querying CivicLens AI")
+    print(f"Audience: {audience}")
+    print(f"Top-K Retrieval: {top_k}")
+    print("-" * 50)
+
+    # 2. Retrieve relevant documents
+    docs = retrieve_documents(
+        query=question,
+        top_k=top_k
+    )
+
+    if not docs:
+        print("No relevant documents found.")
+        return
+
+    # 3. Generate grounded answer
+    answer, summary = generate_answer_and_summary(
+        question=question,
+        documents=docs,
+        audience=audience
+    )
+
+    # 4. Display output
+    print("\nANSWER:\n")
+    print(answer)
+
+    print("\nSUMMARY:\n")
+    print(summary)
+
+    # 5. Optional: show sources for transparency
+    if show_sources:
+        print("\nSOURCES:\n")
+        for i, doc in enumerate(docs, 1):
+            source = doc.metadata.get("source", "unknown")
+            print(f"[{i}] {source}")
+
+
+def run_info(args):
+    """
+    Display CivicLens AI system information.
+    """
+    info_data = {
+        "name": "CivicLens AI",
+        "description": (
+            "A non-partisan AI system that translates complex U.S. government "
+            "documents into clear, age-appropriate explanations."
+        ),
+        "audiences": [
+            "Youth (ages 10-18)",
+            "Policymakers and government leaders"
+        ],
+        "capabilities": [
+            "Retrieval-Augmented Generation (RAG)",
+            "Multi-audience explanations from a single source document",
+            "Transparent source citation",
+            "Document-grounded responses"
+        ],
+        "ethics_and_safeguards": [
+            "No political persuasion or advocacy",
+            "No partisan bias",
+            "Explainable outputs",
+            "Human-in-the-loop oversight"
+        ],
+        "deployment": [
+            "Command-line interface (CLI)",
+            "Chainlit interactive UI",
+            "Local and S3-based document ingestion"
+        ],
+        "mission_alignment": [
+            "AI education",
+            "Civic literacy",
+            "Responsible governance"
+        ]
+    }
+
+    # -------------------------
+    # JSON Output
+    # -------------------------
+    if args.json:
+        import json
+        print(json.dumps(info_data, indent=2))
+        return
+
+    # -------------------------
+    # Short Text Output
+    # -------------------------
+    if args.short:
+        print(
+            "CivicLens AI is a non-partisan AI system that explains U.S. government "
+            "documents in clear, age-appropriate language for youth and policymakers."
+        )
+        return
+
+    # -------------------------
+    # Full Text Output
+    # -------------------------
+    print("""
+CivicLens AI
+============
+
+Purpose
+-------
+CivicLens AI is a non-partisan, responsible AI system designed to improve civic
+literacy by translating complex U.S. government documents—such as Executive
+Orders—into clear, accessible explanations.
+
+Target Audiences
+----------------
+• Youth (ages 10–18)
+• Policymakers and senior government leaders
+
+Core Capabilities
+-----------------
+• Retrieval-Augmented Generation (RAG)
+• Multi-audience explanations from a single source document
+• Transparent source citation and traceability
+• Faithfulness-focused evaluation
+
+Ethics & Safeguards
+------------------
+• No political persuasion or advocacy
+• No partisan bias
+• Document-grounded responses only
+• Explainable and auditable outputs
+• Human oversight for high-impact decisions
+
+Deployment
+----------
+• CLI (argparse-based)
+• Chainlit interactive interface
+• Local and S3 document ingestion
+
+Mission Alignment
+-----------------
+CivicLens AI advances AI education, civic understanding, and responsible use of
+artificial intelligence in governance.
+""")
+

civiclens-0.3.0.dist-info/METADATA

@@ -0,0 +1,166 @@
+Metadata-Version: 2.4
+Name: civiclens
+Version: 0.3.0
+Summary: CivicLens AI – civic education and executive document analysis
+Author-email: Theophilus Siameh <theodondre@gmail.com>
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: argparse>=1.4.0
+Requires-Dist: requests>=2.32.5
+Requires-Dist: rich>=14.2.0
+
+A `Command Line Interface` (CLI) is best understood as a simple language you use to tell a computer what to do. Like natural language, it’s structured around verbs (actions), nouns (things), and modifiers (details).
+
+### CLI Sentence Structure
+  - verb [options] noun [arguments] : Do this action, in this way, to this thing, with these details
+  - `cp report.pdf backup/`
+    - Verb: copy, Noun: source, Noun: destination
+  - `git commit -m "Fix login bug"`
+    - git (tool), commit (verb), -m (modifier), Argument (message)
+  - `docker run -p 8080:80 nginx`
+    - docker (tool), run (verb), Modifier + argument, Noun (image)
+    - 📖 English: `“Run an Nginx container, mapping port 8080 to 80.”`
+
+### Breaking Down CLI Commands
+```md
+When reading or writing a command, ask:
+  - What action do I want? → Verb
+  - On what? → Noun
+  - How exactly? → Options / flags
+  - With what details? → Arguments
+```
+
+### Verb (Command)
+  - The verb tells the system what action to perform.
+```bash
+Examples:
+
+ls → list
+cp → copy
+mv → move
+rm → remove
+git commit → commit changes
+
+Think of verbs as actions.
+```
+
+### Noun (Target / Object)
+  - The noun is what the action is performed on.
+```md
+Examples:
+
+Files: `file.txt`
+Directories: `src/`
+Resources: `origin, main, container`
+```
+
+### Adjectives / Modifiers (Options & Flags)
+  - Modifiers change how the verb behaves.
+  - They usually start with: `- (short flag) -- (long flag)`
+```bash
+Examples:
+
+-l → long format
+-a → include hidden items
+--recursive → apply action recursively
+```
+
+
+## Demo
+```bash
+civiclens --help
+civiclens --version
+
+civiclens ingest \
+    --source s3 \
+    --path s3://eo-archive \
+    --chunk-size 1200
+```
+
+### Example
+```bash 
+civiclens query "How does this EO affect education?" --audience teen
+
+civiclens query "How does this executive order affect education?" \
+  --audience teen \
+  --top-k 5 \
+  --show-sources
+
+civiclens prompt "How does this executive order affect education?" \
+  --temperature 0.0 \
+  --max-tokens 1024 \
+  --model "gpt-oss-20b" \
+  --url "http://localhost:11434/api/chat"
+
+```
+
+### Example
+```bash 
+civiclens eval \
+  --dataset benchmarks/eo_questions.json \
+  --metrics faithfulness answer_relevance context_recall context_precision \
+  --top-k 5 \
+  --save-results
+```
+
+### Add this to TOML
+```bash
+[project]
+name = "civiclens"
+version = "0.1.0"
+description = "CivicLens AI – civic education and executive document analysis"
+requires-python = ">=3.9"
+
+[project.scripts]
+civiclens = "civiclens.cli:main"
+
+[tool.uv]
+package = true
+
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+```
+
+### Install
+```bash
+uv pip install -e .
+
+which civiclens
+
+
+civiclens --help
+civiclens query "How does this EO affect education?"
+civiclens eval --dataset benchmarks/eo_questions.json
+```
+
+### Docker deployment
+```bash
+FROM python:3.11-slim
+
+WORKDIR /app
+COPY . .
+RUN pip install .
+
+ENTRYPOINT ["civiclens"]
+
+
+# To build and run the Docker container 
+docker build -t civiclens-app .
+docker run -it civiclens-app --help
+
+docker run civiclens eval --dataset benchmarks/eo_questions.json
+
+```
+
+### Deploy to PyPI
+```bash
+# Build the package
+uv build
+
+# https://pypi.org/
+
+uv publish --username __token__ --password $PYPI_TOKEN
+
+```
+

civiclens-0.3.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+civiclens/__init__.py,sha256=Pru0BlFBASFCFo7McHdohtKkUtgMPDwbGfyUZlE2_Vw,21
+civiclens/cli.py,sha256=r7T-vK2rjX-QVqzx_-IoAwKc52j8aKL-bkjn5aSUcnc,3619
+civiclens/demo.py,sha256=V14-1pFBNaQoSK94lNfPzsQYTauJTPt1SToguemNeX8,4537
+civiclens/llm.py,sha256=Tj8UOSRQzKLmkK5EcNYzvKCTaKEl3FTu1SnZTcG7WTI,4161
+civiclens/utils.py,sha256=ByCcREoLznpb83nGPLcBs_OcNczw1-3Cae5umqCQE6k,10210
+civiclens-0.3.0.dist-info/METADATA,sha256=bz3akPVpnoi1cBvZuLx_FxWkD3N8kTk-sk4akZNzKPo,3619
+civiclens-0.3.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+civiclens-0.3.0.dist-info/entry_points.txt,sha256=SLVab77DazFUW0bT3GoqKuBMQKHPuCGSxXYej1u7QsE,49
+civiclens-0.3.0.dist-info/top_level.txt,sha256=R-jxhqjzbvdCMGV1x8UBiziQWRes5XLm5rPYJlzk394,10
+civiclens-0.3.0.dist-info/RECORD,,

civiclens-0.3.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

civiclens-0.3.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+civiclens = civiclens.cli:main

civiclens-0.3.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+civiclens